Apache Tomcat - Embedded Servlet Container Configuration

Note that by default, the embedded container attempts to enable the HTTP2 protocol.

1
2
3
4
5
<dependency>
  <groupId>org.apereo.cas</groupId>
  <artifactId>cas-server-webapp-tomcat</artifactId>
  <version>${cas.version}</version>
</dependency>
1
implementation "org.apereo.cas:cas-server-webapp-tomcat:${project.'cas.version'}"
1
2
3
4
5
6
7
8
9
dependencyManagement {
  imports {
    mavenBom "org.apereo.cas:cas-server-support-bom:${project.'cas.version'}"
  }
}

dependencies {  
  implementation "org.apereo.cas:cas-server-webapp-tomcat"
}

IPv4 Configuration

In order to force Apache Tomcat to use IPv4, configure the following as a system property for your run command:

1
-Djava.net.preferIPv4Stack=true 

The same sort of configuration needs to be applied to your $CATALINA_OPTS environment variable in case of an external container.

Faster Startup

This guide provides several recommendations on how to make web applications and Apache Tomcat as a whole to start up faster.

Logging

The embedded Apache Tomcat container is presently unable to display any log messages below INFO even if your CAS log configuration explicitly asks for DEBUG or TRACE level data. See this bug report to learn more.

While workarounds and fixes may become available in the future, for the time being, you may execute the following changes to get DEBUG level log data from the embedded Apache Tomcat. This is specially useful if you are troubleshooting the behavior of Tomcat’s internal components such as valves, etc.

  • Design a logging.properties file as such:
1
2
3
4
handlers = java.util.logging.ConsoleHandler
.level = ALL
java.util.logging.ConsoleHandler.level = FINER
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
  • Design ajava.util.logging.config.file setting as a system/environment variable or command-line argument whose value is set to the logging.properties path. Use the setting when you launch and deploy CAS.

For instance:

1
java -jar /path/to/cas.war -Djava.util.logging.config.file=/path/to/logging.properties

Configuration

The following settings and properties are available from the CAS configuration catalog:

The configuration settings listed below are tagged as Required in the CAS configuration metadata. This flag indicates that the presence of the setting may be needed to activate or affect the behavior of the CAS feature and generally should be reviewed, possibly owned and adjusted. If the setting is assigned a default value, you do not need to strictly put the setting in your copy of the configuration, but should review it nonetheless to make sure it matches your deployment expectations.

The configuration settings listed below are tagged as Optional in the CAS configuration metadata. This flag indicates that the presence of the setting is not immediately necessary in the end-user CAS configuration, because a default value is assigned or the activation of the feature is not conditionally controlled by the setting value.

The configuration settings listed below are tagged as Third Party in the CAS configuration metadata. This flag indicates that the configuration setting is not controlled, owned or managed by the CAS ecosystem, and affects functionality that is offered by a third-party library, such as Spring Boot or Spring Cloud to CAS. For additional info, you might have to visit the third-party source to find more details.

  • server.tomcat.accept-count=100
  • Maximum queue length for incoming connection requests when all possible request processing threads are in use.

    org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat.

  • server.tomcat.accesslog.buffered=true
  • Whether to buffer output such that it is flushed only periodically.

    org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat$Accesslog.

  • server.tomcat.accesslog.check-exists=false
  • Whether to check for log file existence so it can be recreated it if an external process has renamed it.

    org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat$Accesslog.

  • server.tomcat.accesslog.condition-if=
  • Whether logging of the request will only be enabled if "ServletRequest.getAttribute(conditionIf)" does not yield null.

    org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat$Accesslog.

  • server.tomcat.accesslog.condition-unless=
  • Whether logging of the request will only be enabled if "ServletRequest.getAttribute(conditionUnless)" yield null.

    org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat$Accesslog.

  • server.tomcat.accesslog.directory=logs
  • Directory in which log files are created. Can be absolute or relative to the Tomcat base dir.

    org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat$Accesslog.

  • server.tomcat.accesslog.enabled=false
  • Enable access log.

    org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat$Accesslog.

  • server.tomcat.accesslog.encoding=
  • Character set used by the log file. Default to the system default character set.

    org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat$Accesslog.

  • server.tomcat.accesslog.file-date-format=.yyyy-MM-dd
  • Date format to place in the log file name.

    org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat$Accesslog.

  • server.tomcat.accesslog.ipv6-canonical=false
  • Whether to use IPv6 canonical representation format as defined by RFC 5952.

    org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat$Accesslog.

  • server.tomcat.accesslog.locale=
  • Locale used to format timestamps in log entries and in log file name suffix. Default to the default locale of the Java process.

    org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat$Accesslog.

  • server.tomcat.accesslog.max-days=-1
  • Number of days to retain the access log files before they are removed.

    org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat$Accesslog.

  • server.tomcat.accesslog.pattern=common
  • Format pattern for access logs.

    org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat$Accesslog.

  • server.tomcat.accesslog.prefix=access_log
  • Log file name prefix.

    org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat$Accesslog.

  • server.tomcat.accesslog.rename-on-rotate=false
  • Whether to defer inclusion of the date stamp in the file name until rotate time.

    org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat$Accesslog.

  • server.tomcat.accesslog.request-attributes-enabled=false
  • Set request attributes for the IP address, Hostname, protocol, and port used for the request.

    org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat$Accesslog.

  • server.tomcat.accesslog.rotate=true
  • Whether to enable access log rotation.

    org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat$Accesslog.

  • server.tomcat.accesslog.suffix=.log
  • Log file name suffix.

    org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat$Accesslog.

  • server.tomcat.additional-tld-skip-patterns=
  • Comma-separated list of additional patterns that match jars to ignore for TLD scanning. The special '?' and '*' characters can be used in the pattern to match one and only one character and zero or more characters respectively.

    org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat.

  • server.tomcat.background-processor-delay=10s
  • Delay between the invocation of backgroundProcess methods. If a duration suffix is not specified, seconds will be used.

    org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat.

  • server.tomcat.basedir=
  • Tomcat base directory. If not specified, a temporary directory is used.

    org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat.

  • server.tomcat.connection-timeout=
  • Amount of time the connector will wait, after accepting a connection, for the request URI line to be presented.

    org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat.

  • server.tomcat.keep-alive-timeout=
  • Time to wait for another HTTP request before the connection is closed. When not set the connectionTimeout is used. When set to -1 there will be no timeout.

    org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat.

  • server.tomcat.max-connections=8192
  • Maximum number of connections that the server accepts and processes at any given time. Once the limit has been reached, the operating system may still accept connections based on the "acceptCount" property.

    org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat.

  • server.tomcat.max-http-form-post-size=2MB
  • Maximum size of the form content in any HTTP post request.

    org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat.

  • server.tomcat.max-http-post-size=
  • Deprecation status is ERROR with a replacement setting: server.tomcat.max-http-form-post-size.

  • server.tomcat.max-keep-alive-requests=100
  • Maximum number of HTTP requests that can be pipelined before the connection is closed. When set to 0 or 1, keep-alive and pipelining are disabled. When set to -1, an unlimited number of pipelined or keep-alive requests are allowed.

    org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat.

  • server.tomcat.max-swallow-size=2MB
  • Maximum amount of request body to swallow.

    org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat.

  • server.tomcat.mbeanregistry.enabled=false
  • Whether Tomcat's MBean Registry should be enabled.

    org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat$Mbeanregistry.

  • server.tomcat.processor-cache=200
  • Maximum number of idle processors that will be retained in the cache and reused with a subsequent request. When set to -1 the cache will be unlimited with a theoretical maximum size equal to the maximum number of connections.

    org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat.

  • server.tomcat.redirect-context-root=true
  • Whether requests to the context root should be redirected by appending a / to the path. When using SSL terminated at a proxy, this property should be set to false.

    org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat.

  • server.tomcat.relaxed-path-chars=
  • Comma-separated list of additional unencoded characters that should be allowed in URI paths. Only "< > [ \ ] ^ ` | </code>" are allowed.

    org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat.

  • server.tomcat.relaxed-query-chars=
  • Comma-separated list of additional unencoded characters that should be allowed in URI query strings. Only "< > [ \ ] ^ ` | </code>" are allowed.

    org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat.

  • server.tomcat.remoteip.host-header=X-Forwarded-Host
  • Name of the HTTP header from which the remote host is extracted.

    org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat$Remoteip.

  • server.tomcat.remoteip.internal-proxies=10\.\d{1,3}\.\d{1,3}\.\d{1,3}|192\.168\.\d{1,3}\.\d{1,3}|169\.254\.\d{1,3}\.\d{1,3}|127\.\d{1,3}\.\d{1,3}\.\d{1,3}|172\.1[6-9]{1}\.\d{1,3}\.\d{1,3}|172\.2[0-9]{1}\.\d{1,3}\.\d{1,3}|172\.3[0-1]{1}\.\d{1,3}\.\d{1,3}|0:0:0:0:0:0:0:1|::1
  • Regular expression that matches proxies that are to be trusted.

    org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat$Remoteip.

  • server.tomcat.remoteip.port-header=X-Forwarded-Port
  • Name of the HTTP header used to override the original port value.

    org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat$Remoteip.

  • server.tomcat.remoteip.protocol-header=
  • Header that holds the incoming protocol, usually named "X-Forwarded-Proto".

    org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat$Remoteip.

  • server.tomcat.remoteip.protocol-header-https-value=https
  • Value of the protocol header indicating whether the incoming request uses SSL.

    org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat$Remoteip.

  • server.tomcat.remoteip.remote-ip-header=
  • Name of the HTTP header from which the remote IP is extracted. For instance, `X-FORWARDED-FOR`.

    org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat$Remoteip.

  • server.tomcat.resource.allow-caching=true
  • Whether static resource caching is permitted for this web application.

    org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat$Resource.

  • server.tomcat.resource.cache-ttl=
  • Time-to-live of the static resource cache.

    org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat$Resource.

  • server.tomcat.threads.max=200
  • Maximum amount of worker threads.

    org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat$Threads.

  • server.tomcat.threads.min-spare=10
  • Minimum amount of worker threads.

    org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat$Threads.

  • server.tomcat.uri-encoding=UTF-8
  • Character encoding to use to decode the URI.

    org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat.

  • server.tomcat.use-relative-redirects=false
  • Whether HTTP 1.1 and later location headers generated by a call to sendRedirect will use relative or absolute redirects.

    org.springframework.boot.autoconfigure.web.ServerProperties$Tomcat.

    Configuration Metadata

    The collection of configuration properties listed in this section are automatically generated from the CAS source and components that contain the actual field definitions, types, descriptions, modules, etc. This metadata may not always be 100% accurate, or could be lacking details and sufficient explanations.

    Be Selective

    This section is meant as a guide only. Do NOT copy/paste the entire collection of settings into your CAS configuration; rather pick only the properties that you need. Do NOT enable settings unless you are certain of their purpose and do NOT copy settings into your configuration only to keep them as reference. All these ideas lead to upgrade headaches, maintenance nightmares and premature aging.

    YAGNI

    Note that for nearly ALL use cases, declaring and configuring properties listed here is sufficient. You should NOT have to explicitly massage a CAS XML/Java/etc configuration file to design an authentication handler, create attribute release policies, etc. CAS at runtime will auto-configure all required changes for you. If you are unsure about the meaning of a given CAS setting, do NOT turn it on without hesitation. Review the codebase or better yet, ask questions to clarify the intended behavior.

    Naming Convention

    Property names can be specified in very relaxed terms. For instance cas.someProperty, cas.some-property, cas.some_property are all valid names. While all forms are accepted by CAS, there are certain components (in CAS and other frameworks used) whose activation at runtime is conditional on a property value, where this property is required to have been specified in CAS configuration using kebab case. This is both true for properties that are owned by CAS as well as those that might be presented to the system via an external library or framework such as Spring Boot, etc. When possible, properties should be stored in lower-case kebab format, such as cas.property-name=value.S ettings and properties that are controlled by the CAS platform directly always begin with the prefix cas. All other settings are controlled and provided to CAS via other underlying frameworks and may have their own schemas and syntax. BE CAREFUL with the distinction. Unrecognized properties are rejected by CAS and/or frameworks upon which CAS depends. This means if you somehow misspell a property definition or fail to adhere to the dot-notation syntax and such, your setting is entirely refused by CAS and likely the feature it controls will never be activated in the way you intend.

    Validation

    Configuration properties are automatically validated on CAS startup to report issues with configuration binding, specially if defined CAS settings cannot be recognized or validated by the configuration schema. The validation process is on by default and can be skipped on startup using a special system property SKIP_CONFIG_VALIDATION that should be set to true. Additional validation processes are also handled via Configuration Metadata and property migrations applied automatically on startup by Spring Boot and family.

    Indexed Settings

    CAS settings able to accept multiple values are typically documented with an index, such as cas.some.setting[0]=value. The index [0] is meant to be incremented by the adopter to allow for distinct multiple configuration blocks.

    HTTP Proxying

    The following settings and properties are available from the CAS configuration catalog:

    The configuration settings listed below are tagged as Required in the CAS configuration metadata. This flag indicates that the presence of the setting may be needed to activate or affect the behavior of the CAS feature and generally should be reviewed, possibly owned and adjusted. If the setting is assigned a default value, you do not need to strictly put the setting in your copy of the configuration, but should review it nonetheless to make sure it matches your deployment expectations.

  • cas.server.tomcat.http-proxy.enabled=false
  • Enable the container running in proxy mode.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatHttpProxyProperties.

    The configuration settings listed below are tagged as Optional in the CAS configuration metadata. This flag indicates that the presence of the setting is not immediately necessary in the end-user CAS configuration, because a default value is assigned or the activation of the feature is not conditionally controlled by the setting value.

  • cas.server.tomcat.http-proxy.attributes=
  • Custom attributes to set on the proxy connector.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatHttpProxyProperties.

  • cas.server.tomcat.http-proxy.protocol=AJP/1.3
  • Proxy protocol to use.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatHttpProxyProperties.

  • cas.server.tomcat.http-proxy.proxy-port=0
  • Proxy port for the proxy.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatHttpProxyProperties.

  • cas.server.tomcat.http-proxy.redirect-port=0
  • Redirect port for the proxy.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatHttpProxyProperties.

  • cas.server.tomcat.http-proxy.scheme=https
  • Scheme used for the proxy.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatHttpProxyProperties.

  • cas.server.tomcat.http-proxy.secret=
  • Set the secret that must be included with every request.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatHttpProxyProperties.

  • cas.server.tomcat.http-proxy.secure=true
  • Whether proxy should run in secure mode.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatHttpProxyProperties.

    Configuration Metadata

    The collection of configuration properties listed in this section are automatically generated from the CAS source and components that contain the actual field definitions, types, descriptions, modules, etc. This metadata may not always be 100% accurate, or could be lacking details and sufficient explanations.

    Be Selective

    This section is meant as a guide only. Do NOT copy/paste the entire collection of settings into your CAS configuration; rather pick only the properties that you need. Do NOT enable settings unless you are certain of their purpose and do NOT copy settings into your configuration only to keep them as reference. All these ideas lead to upgrade headaches, maintenance nightmares and premature aging.

    YAGNI

    Note that for nearly ALL use cases, declaring and configuring properties listed here is sufficient. You should NOT have to explicitly massage a CAS XML/Java/etc configuration file to design an authentication handler, create attribute release policies, etc. CAS at runtime will auto-configure all required changes for you. If you are unsure about the meaning of a given CAS setting, do NOT turn it on without hesitation. Review the codebase or better yet, ask questions to clarify the intended behavior.

    Naming Convention

    Property names can be specified in very relaxed terms. For instance cas.someProperty, cas.some-property, cas.some_property are all valid names. While all forms are accepted by CAS, there are certain components (in CAS and other frameworks used) whose activation at runtime is conditional on a property value, where this property is required to have been specified in CAS configuration using kebab case. This is both true for properties that are owned by CAS as well as those that might be presented to the system via an external library or framework such as Spring Boot, etc. When possible, properties should be stored in lower-case kebab format, such as cas.property-name=value.S ettings and properties that are controlled by the CAS platform directly always begin with the prefix cas. All other settings are controlled and provided to CAS via other underlying frameworks and may have their own schemas and syntax. BE CAREFUL with the distinction. Unrecognized properties are rejected by CAS and/or frameworks upon which CAS depends. This means if you somehow misspell a property definition or fail to adhere to the dot-notation syntax and such, your setting is entirely refused by CAS and likely the feature it controls will never be activated in the way you intend.

    Validation

    Configuration properties are automatically validated on CAS startup to report issues with configuration binding, specially if defined CAS settings cannot be recognized or validated by the configuration schema. The validation process is on by default and can be skipped on startup using a special system property SKIP_CONFIG_VALIDATION that should be set to true. Additional validation processes are also handled via Configuration Metadata and property migrations applied automatically on startup by Spring Boot and family.

    Indexed Settings

    CAS settings able to accept multiple values are typically documented with an index, such as cas.some.setting[0]=value. The index [0] is meant to be incremented by the adopter to allow for distinct multiple configuration blocks.

    HTTP

    The following settings and properties are available from the CAS configuration catalog:

    The configuration settings listed below are tagged as Required in the CAS configuration metadata. This flag indicates that the presence of the setting may be needed to activate or affect the behavior of the CAS feature and generally should be reviewed, possibly owned and adjusted. If the setting is assigned a default value, you do not need to strictly put the setting in your copy of the configuration, but should review it nonetheless to make sure it matches your deployment expectations.

  • cas.server.tomcat.http.enabled=false
  • Enable a separate port for the embedded container for HTTP access.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatHttpProperties.

    The configuration settings listed below are tagged as Optional in the CAS configuration metadata. This flag indicates that the presence of the setting is not immediately necessary in the end-user CAS configuration, because a default value is assigned or the activation of the feature is not conditionally controlled by the setting value.

  • cas.server.tomcat.http.attributes=
  • Additional attributes to be set on the connector.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatHttpProperties.

  • cas.server.tomcat.http.port=8080
  • The HTTP port to use.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatHttpProperties.

  • cas.server.tomcat.http.protocol=org.apache.coyote.http11.Http11NioProtocol
  • HTTP protocol to use.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatHttpProperties.

  • cas.server.tomcat.http.redirect-port=0
  • If this Connector is supporting non-SSL requests, this will automatically redirect the request to the port number specified here. Matching security constraints that require SSL transport will be auto-defined.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatHttpProperties.

    Configuration Metadata

    The collection of configuration properties listed in this section are automatically generated from the CAS source and components that contain the actual field definitions, types, descriptions, modules, etc. This metadata may not always be 100% accurate, or could be lacking details and sufficient explanations.

    Be Selective

    This section is meant as a guide only. Do NOT copy/paste the entire collection of settings into your CAS configuration; rather pick only the properties that you need. Do NOT enable settings unless you are certain of their purpose and do NOT copy settings into your configuration only to keep them as reference. All these ideas lead to upgrade headaches, maintenance nightmares and premature aging.

    YAGNI

    Note that for nearly ALL use cases, declaring and configuring properties listed here is sufficient. You should NOT have to explicitly massage a CAS XML/Java/etc configuration file to design an authentication handler, create attribute release policies, etc. CAS at runtime will auto-configure all required changes for you. If you are unsure about the meaning of a given CAS setting, do NOT turn it on without hesitation. Review the codebase or better yet, ask questions to clarify the intended behavior.

    Naming Convention

    Property names can be specified in very relaxed terms. For instance cas.someProperty, cas.some-property, cas.some_property are all valid names. While all forms are accepted by CAS, there are certain components (in CAS and other frameworks used) whose activation at runtime is conditional on a property value, where this property is required to have been specified in CAS configuration using kebab case. This is both true for properties that are owned by CAS as well as those that might be presented to the system via an external library or framework such as Spring Boot, etc. When possible, properties should be stored in lower-case kebab format, such as cas.property-name=value.S ettings and properties that are controlled by the CAS platform directly always begin with the prefix cas. All other settings are controlled and provided to CAS via other underlying frameworks and may have their own schemas and syntax. BE CAREFUL with the distinction. Unrecognized properties are rejected by CAS and/or frameworks upon which CAS depends. This means if you somehow misspell a property definition or fail to adhere to the dot-notation syntax and such, your setting is entirely refused by CAS and likely the feature it controls will never be activated in the way you intend.

    Validation

    Configuration properties are automatically validated on CAS startup to report issues with configuration binding, specially if defined CAS settings cannot be recognized or validated by the configuration schema. The validation process is on by default and can be skipped on startup using a special system property SKIP_CONFIG_VALIDATION that should be set to true. Additional validation processes are also handled via Configuration Metadata and property migrations applied automatically on startup by Spring Boot and family.

    Indexed Settings

    CAS settings able to accept multiple values are typically documented with an index, such as cas.some.setting[0]=value. The index [0] is meant to be incremented by the adopter to allow for distinct multiple configuration blocks.

    AJP

    The following settings and properties are available from the CAS configuration catalog:

    The configuration settings listed below are tagged as Required in the CAS configuration metadata. This flag indicates that the presence of the setting may be needed to activate or affect the behavior of the CAS feature and generally should be reviewed, possibly owned and adjusted. If the setting is assigned a default value, you do not need to strictly put the setting in your copy of the configuration, but should review it nonetheless to make sure it matches your deployment expectations.

  • cas.server.tomcat.ajp.enabled=false
  • Enable AJP support in CAS for the embedded Apache Tomcat container.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatAjpProperties.

    The configuration settings listed below are tagged as Optional in the CAS configuration metadata. This flag indicates that the presence of the setting is not immediately necessary in the end-user CAS configuration, because a default value is assigned or the activation of the feature is not conditionally controlled by the setting value.

  • cas.server.tomcat.ajp.allow-trace=false
  • A boolean value which can be used to enable or disable the TRACE HTTP method. If not specified, this attribute is set to false.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatAjpProperties.

  • cas.server.tomcat.ajp.async-timeout=PT5S
  • The default timeout for asynchronous requests in milliseconds. If not specified, this attribute is set to 10000 (10 seconds).

    This settings supports the java.time.Duration syntax [?].

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatAjpProperties.

  • cas.server.tomcat.ajp.attributes=
  • Additional attributes to be set on the AJP connector in form of key-value pairs. Examples include:

    • tomcatAuthentication: If set to true, the authentication will be done in Tomcat. Otherwise, the authenticated principal will be propagated from the native webserver and used for authorization in Tomcat. Note that this principal will have no roles associated with it. The default value is true.
    • maxThreads: The maximum number of request processing threads to be created by this Connector, which therefore determines the maximum number of simultaneous requests that can be handled. If not specified, this attribute is set to 200. If an executor is associated with this connector, this attribute is ignored as the connector will execute tasks using the executor rather than an internal thread pool.
    • keepAliveTimeout: The number of milliseconds this Connector will wait for another AJP request before closing the connection. The default value is to use the value that has been set for the connectionTimeout attribute.
    • maxCookieCount: The maximum number of cookies that are permitted for a request. A value of less than zero means no limit. If not specified, a default value of 200 will be used.
    • bufferSize: The size of the output buffer to use. If less than or equal to zero, then output buffering is disabled. The default value is -1 (i.e. buffering disabled)
    • clientCertProvider: When client certificate information is presented in a form other than instances of java.security.cert.X509Certificate it needs to be converted before it can be used and this property controls which JSSE provider is used to perform the conversion. For example it is used with the AJP connectors, the HTTP APR connector and with the org.apache.catalina.valves.SSLValve.If not specified, the default provider will be used.
    • connectionTimeout: The number of milliseconds this Connector will wait, after accepting a connection, for the request URI line to be presented. The default value is infinite (i.e. no timeout).
    • address: For servers with more than one IP address, this attribute specifies which address will be used for listening on the specified port. By default, this port will be used on all IP addresses associated with the server. A value of 127.0.0.1 indicates that the Connector will only listen on the loopback interface.

    See the Apache Tomcat documentation for a full list.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatAjpProperties.

  • cas.server.tomcat.ajp.enable-lookups=false
  • Set to true if you want calls to request.getRemoteHost() to perform DNS lookups in order to return the actual host name of the remote client. Set to false to skip the DNS lookup and return the IP address in String form instead (thereby improving performance). By default, DNS lookups are disabled.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatAjpProperties.

  • cas.server.tomcat.ajp.max-post-size=20971520
  • The maximum size in bytes of the POST which will be handled by the container FORM URL parameter parsing. The feature can be disabled by setting this attribute to a value less than or equal to 0. If not specified, this attribute is set to 2097152 (2 megabytes).

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatAjpProperties.

  • cas.server.tomcat.ajp.port=8009
  • The TCP port number on which this Connector will create a server socket and await incoming connections. Your operating system will allow only one server application to listen to a particular port number on a particular IP address. If the special value of 0 (zero) is used, then Tomcat will select a free port at random to use for this connector. This is typically only useful in embedded and testing applications.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatAjpProperties.

  • cas.server.tomcat.ajp.protocol=AJP/1.3
  • Sets the protocol to handle incoming traffic.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatAjpProperties.

  • cas.server.tomcat.ajp.proxy-port=-1
  • If this Connector is being used in a proxy configuration, configure this attribute to specify the server port to be returned for calls to request.getServerPort().

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatAjpProperties.

  • cas.server.tomcat.ajp.redirect-port=-1
  • If this Connector is supporting non-SSL requests, and a request is received for which a matching security-constraint requires SSL transport, Catalina will automatically redirect the request to the port number specified here.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatAjpProperties.

  • cas.server.tomcat.ajp.scheme=http
  • Set this attribute to the name of the protocol you wish to have returned by calls to request.getScheme(). For example, you would set this attribute to https for an SSL Connector.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatAjpProperties.

  • cas.server.tomcat.ajp.secret=
  • Set the secret that must be included with every request.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatAjpProperties.

  • cas.server.tomcat.ajp.secure=false
  • Set this attribute to true if you wish to have calls to request.isSecure() to return true for requests received by this Connector (you would want this on an SSL Connector). The default value is false.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatAjpProperties.

    Configuration Metadata

    The collection of configuration properties listed in this section are automatically generated from the CAS source and components that contain the actual field definitions, types, descriptions, modules, etc. This metadata may not always be 100% accurate, or could be lacking details and sufficient explanations.

    Be Selective

    This section is meant as a guide only. Do NOT copy/paste the entire collection of settings into your CAS configuration; rather pick only the properties that you need. Do NOT enable settings unless you are certain of their purpose and do NOT copy settings into your configuration only to keep them as reference. All these ideas lead to upgrade headaches, maintenance nightmares and premature aging.

    YAGNI

    Note that for nearly ALL use cases, declaring and configuring properties listed here is sufficient. You should NOT have to explicitly massage a CAS XML/Java/etc configuration file to design an authentication handler, create attribute release policies, etc. CAS at runtime will auto-configure all required changes for you. If you are unsure about the meaning of a given CAS setting, do NOT turn it on without hesitation. Review the codebase or better yet, ask questions to clarify the intended behavior.

    Naming Convention

    Property names can be specified in very relaxed terms. For instance cas.someProperty, cas.some-property, cas.some_property are all valid names. While all forms are accepted by CAS, there are certain components (in CAS and other frameworks used) whose activation at runtime is conditional on a property value, where this property is required to have been specified in CAS configuration using kebab case. This is both true for properties that are owned by CAS as well as those that might be presented to the system via an external library or framework such as Spring Boot, etc. When possible, properties should be stored in lower-case kebab format, such as cas.property-name=value.S ettings and properties that are controlled by the CAS platform directly always begin with the prefix cas. All other settings are controlled and provided to CAS via other underlying frameworks and may have their own schemas and syntax. BE CAREFUL with the distinction. Unrecognized properties are rejected by CAS and/or frameworks upon which CAS depends. This means if you somehow misspell a property definition or fail to adhere to the dot-notation syntax and such, your setting is entirely refused by CAS and likely the feature it controls will never be activated in the way you intend.

    Validation

    Configuration properties are automatically validated on CAS startup to report issues with configuration binding, specially if defined CAS settings cannot be recognized or validated by the configuration schema. The validation process is on by default and can be skipped on startup using a special system property SKIP_CONFIG_VALIDATION that should be set to true. Additional validation processes are also handled via Configuration Metadata and property migrations applied automatically on startup by Spring Boot and family.

    Indexed Settings

    CAS settings able to accept multiple values are typically documented with an index, such as cas.some.setting[0]=value. The index [0] is meant to be incremented by the adopter to allow for distinct multiple configuration blocks.

    SSL Valve

    The Apache Tomcat SSLValve is a way to get a client certificate from an SSL proxy (e.g. HAProxy or BigIP F5) running in front of Tomcat via an HTTP header. If you enable this, make sure your proxy is ensuring that this header does not originate with the client (e.g. the browser).

    The following settings and properties are available from the CAS configuration catalog:

    The configuration settings listed below are tagged as Required in the CAS configuration metadata. This flag indicates that the presence of the setting may be needed to activate or affect the behavior of the CAS feature and generally should be reviewed, possibly owned and adjusted. If the setting is assigned a default value, you do not need to strictly put the setting in your copy of the configuration, but should review it nonetheless to make sure it matches your deployment expectations.

  • cas.server.tomcat.ssl-valve.enabled=false
  • Enable the SSL valve for apache tomcat.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatSslValveProperties.

    The configuration settings listed below are tagged as Optional in the CAS configuration metadata. This flag indicates that the presence of the setting is not immediately necessary in the end-user CAS configuration, because a default value is assigned or the activation of the feature is not conditionally controlled by the setting value.

  • cas.server.tomcat.ssl-valve.ssl-cipher-header=ssl_cipher
  • Allows setting a custom name for the ssl_cipher header. If not specified, the default of ssl_cipher is used.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatSslValveProperties.

  • cas.server.tomcat.ssl-valve.ssl-cipher-user-key-size-header=ssl_cipher_usekeysize
  • Allows setting a custom name for the ssl_cipher_usekeysize header. If not specified, the default of ssl_cipher_usekeysize is used.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatSslValveProperties.

  • cas.server.tomcat.ssl-valve.ssl-client-cert-header=ssl_client_cert
  • Allows setting a custom name for the ssl_client_cert header. If not specified, the default of ssl_client_cert is used.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatSslValveProperties.

  • cas.server.tomcat.ssl-valve.ssl-session-id-header=ssl_session_id
  • Allows setting a custom name for the ssl_session_id header. If not specified, the default of ssl_session_id is used.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatSslValveProperties.

    Configuration Metadata

    The collection of configuration properties listed in this section are automatically generated from the CAS source and components that contain the actual field definitions, types, descriptions, modules, etc. This metadata may not always be 100% accurate, or could be lacking details and sufficient explanations.

    Be Selective

    This section is meant as a guide only. Do NOT copy/paste the entire collection of settings into your CAS configuration; rather pick only the properties that you need. Do NOT enable settings unless you are certain of their purpose and do NOT copy settings into your configuration only to keep them as reference. All these ideas lead to upgrade headaches, maintenance nightmares and premature aging.

    YAGNI

    Note that for nearly ALL use cases, declaring and configuring properties listed here is sufficient. You should NOT have to explicitly massage a CAS XML/Java/etc configuration file to design an authentication handler, create attribute release policies, etc. CAS at runtime will auto-configure all required changes for you. If you are unsure about the meaning of a given CAS setting, do NOT turn it on without hesitation. Review the codebase or better yet, ask questions to clarify the intended behavior.

    Naming Convention

    Property names can be specified in very relaxed terms. For instance cas.someProperty, cas.some-property, cas.some_property are all valid names. While all forms are accepted by CAS, there are certain components (in CAS and other frameworks used) whose activation at runtime is conditional on a property value, where this property is required to have been specified in CAS configuration using kebab case. This is both true for properties that are owned by CAS as well as those that might be presented to the system via an external library or framework such as Spring Boot, etc. When possible, properties should be stored in lower-case kebab format, such as cas.property-name=value.S ettings and properties that are controlled by the CAS platform directly always begin with the prefix cas. All other settings are controlled and provided to CAS via other underlying frameworks and may have their own schemas and syntax. BE CAREFUL with the distinction. Unrecognized properties are rejected by CAS and/or frameworks upon which CAS depends. This means if you somehow misspell a property definition or fail to adhere to the dot-notation syntax and such, your setting is entirely refused by CAS and likely the feature it controls will never be activated in the way you intend.

    Validation

    Configuration properties are automatically validated on CAS startup to report issues with configuration binding, specially if defined CAS settings cannot be recognized or validated by the configuration schema. The validation process is on by default and can be skipped on startup using a special system property SKIP_CONFIG_VALIDATION that should be set to true. Additional validation processes are also handled via Configuration Metadata and property migrations applied automatically on startup by Spring Boot and family.

    Indexed Settings

    CAS settings able to accept multiple values are typically documented with an index, such as cas.some.setting[0]=value. The index [0] is meant to be incremented by the adopter to allow for distinct multiple configuration blocks.

    Example HAProxy Configuration (snippet): Configure SSL frontend with cert optional, redirect to cas, if cert provided, put it on header.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    
    frontend web-vip
      bind 192.168.2.10:443 ssl crt /var/lib/haproxy/certs/www.example.com.pem ca-file /var/lib/haproxy/certs/ca.pem verify optional
      mode http
      acl www-cert ssl_fc_sni if { www.example.com }
      acl empty-path path /
      http-request redirect location /cas/ if empty-path www-cert
      http-request del-header ssl_client_cert unless { ssl_fc_has_crt }
      http-request set-header ssl_client_cert -----BEGIN\ CERTIFICATE-----\ %[ssl_c_der,base64]\ -----END\ CERTIFICATE-----\  if { ssl_fc_has_crt }
      acl cas-path path_beg -i /cas
      reqadd X-Forwarded-Proto:\ https
      use_backend cas-pool if cas-path
    
    backend cas-pool
      option httpclose
      option forwardfor
      cookie SERVERID-cas insert indirect nocache
      server cas-1 192.168.2.10:8080 check cookie cas-1
    

    Extended Access Log Valve

    The following settings and properties are available from the CAS configuration catalog:

    The configuration settings listed below are tagged as Required in the CAS configuration metadata. This flag indicates that the presence of the setting may be needed to activate or affect the behavior of the CAS feature and generally should be reviewed, possibly owned and adjusted. If the setting is assigned a default value, you do not need to strictly put the setting in your copy of the configuration, but should review it nonetheless to make sure it matches your deployment expectations.

  • cas.server.tomcat.ext-access-log.enabled=false
  • Flag to indicate whether extended log facility is enabled.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatExtendedAccessLogProperties.

    The configuration settings listed below are tagged as Optional in the CAS configuration metadata. This flag indicates that the presence of the setting is not immediately necessary in the end-user CAS configuration, because a default value is assigned or the activation of the feature is not conditionally controlled by the setting value.

  • cas.server.tomcat.ext-access-log.directory=
  • Directory name for extended log.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatExtendedAccessLogProperties.

  • cas.server.tomcat.ext-access-log.pattern=c-ip s-ip cs-uri sc-status time x-threadname x-H(secure) x-H(remoteUser)
  • String representing extended log pattern.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatExtendedAccessLogProperties.

  • cas.server.tomcat.ext-access-log.prefix=localhost_access_extended
  • File name prefix for extended log.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatExtendedAccessLogProperties.

  • cas.server.tomcat.ext-access-log.suffix=.log
  • File name suffix for extended log.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatExtendedAccessLogProperties.

    Configuration Metadata

    The collection of configuration properties listed in this section are automatically generated from the CAS source and components that contain the actual field definitions, types, descriptions, modules, etc. This metadata may not always be 100% accurate, or could be lacking details and sufficient explanations.

    Be Selective

    This section is meant as a guide only. Do NOT copy/paste the entire collection of settings into your CAS configuration; rather pick only the properties that you need. Do NOT enable settings unless you are certain of their purpose and do NOT copy settings into your configuration only to keep them as reference. All these ideas lead to upgrade headaches, maintenance nightmares and premature aging.

    YAGNI

    Note that for nearly ALL use cases, declaring and configuring properties listed here is sufficient. You should NOT have to explicitly massage a CAS XML/Java/etc configuration file to design an authentication handler, create attribute release policies, etc. CAS at runtime will auto-configure all required changes for you. If you are unsure about the meaning of a given CAS setting, do NOT turn it on without hesitation. Review the codebase or better yet, ask questions to clarify the intended behavior.

    Naming Convention

    Property names can be specified in very relaxed terms. For instance cas.someProperty, cas.some-property, cas.some_property are all valid names. While all forms are accepted by CAS, there are certain components (in CAS and other frameworks used) whose activation at runtime is conditional on a property value, where this property is required to have been specified in CAS configuration using kebab case. This is both true for properties that are owned by CAS as well as those that might be presented to the system via an external library or framework such as Spring Boot, etc. When possible, properties should be stored in lower-case kebab format, such as cas.property-name=value.S ettings and properties that are controlled by the CAS platform directly always begin with the prefix cas. All other settings are controlled and provided to CAS via other underlying frameworks and may have their own schemas and syntax. BE CAREFUL with the distinction. Unrecognized properties are rejected by CAS and/or frameworks upon which CAS depends. This means if you somehow misspell a property definition or fail to adhere to the dot-notation syntax and such, your setting is entirely refused by CAS and likely the feature it controls will never be activated in the way you intend.

    Validation

    Configuration properties are automatically validated on CAS startup to report issues with configuration binding, specially if defined CAS settings cannot be recognized or validated by the configuration schema. The validation process is on by default and can be skipped on startup using a special system property SKIP_CONFIG_VALIDATION that should be set to true. Additional validation processes are also handled via Configuration Metadata and property migrations applied automatically on startup by Spring Boot and family.

    Indexed Settings

    CAS settings able to accept multiple values are typically documented with an index, such as cas.some.setting[0]=value. The index [0] is meant to be incremented by the adopter to allow for distinct multiple configuration blocks.

    Rewrite Valve

    The following settings and properties are available from the CAS configuration catalog:

    The configuration settings listed below are tagged as Required in the CAS configuration metadata. This flag indicates that the presence of the setting may be needed to activate or affect the behavior of the CAS feature and generally should be reviewed, possibly owned and adjusted. If the setting is assigned a default value, you do not need to strictly put the setting in your copy of the configuration, but should review it nonetheless to make sure it matches your deployment expectations.

  • cas.server.tomcat.rewrite-valve.location=
  • Location of a rewrite valve specifically by Apache Tomcat to activate URL rewriting.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatRewriteValveProperties.

    The configuration settings listed below are tagged as Optional in the CAS configuration metadata. This flag indicates that the presence of the setting is not immediately necessary in the end-user CAS configuration, because a default value is assigned or the activation of the feature is not conditionally controlled by the setting value.

    Configuration Metadata

    The collection of configuration properties listed in this section are automatically generated from the CAS source and components that contain the actual field definitions, types, descriptions, modules, etc. This metadata may not always be 100% accurate, or could be lacking details and sufficient explanations.

    Be Selective

    This section is meant as a guide only. Do NOT copy/paste the entire collection of settings into your CAS configuration; rather pick only the properties that you need. Do NOT enable settings unless you are certain of their purpose and do NOT copy settings into your configuration only to keep them as reference. All these ideas lead to upgrade headaches, maintenance nightmares and premature aging.

    YAGNI

    Note that for nearly ALL use cases, declaring and configuring properties listed here is sufficient. You should NOT have to explicitly massage a CAS XML/Java/etc configuration file to design an authentication handler, create attribute release policies, etc. CAS at runtime will auto-configure all required changes for you. If you are unsure about the meaning of a given CAS setting, do NOT turn it on without hesitation. Review the codebase or better yet, ask questions to clarify the intended behavior.

    Naming Convention

    Property names can be specified in very relaxed terms. For instance cas.someProperty, cas.some-property, cas.some_property are all valid names. While all forms are accepted by CAS, there are certain components (in CAS and other frameworks used) whose activation at runtime is conditional on a property value, where this property is required to have been specified in CAS configuration using kebab case. This is both true for properties that are owned by CAS as well as those that might be presented to the system via an external library or framework such as Spring Boot, etc. When possible, properties should be stored in lower-case kebab format, such as cas.property-name=value.S ettings and properties that are controlled by the CAS platform directly always begin with the prefix cas. All other settings are controlled and provided to CAS via other underlying frameworks and may have their own schemas and syntax. BE CAREFUL with the distinction. Unrecognized properties are rejected by CAS and/or frameworks upon which CAS depends. This means if you somehow misspell a property definition or fail to adhere to the dot-notation syntax and such, your setting is entirely refused by CAS and likely the feature it controls will never be activated in the way you intend.

    Validation

    Configuration properties are automatically validated on CAS startup to report issues with configuration binding, specially if defined CAS settings cannot be recognized or validated by the configuration schema. The validation process is on by default and can be skipped on startup using a special system property SKIP_CONFIG_VALIDATION that should be set to true. Additional validation processes are also handled via Configuration Metadata and property migrations applied automatically on startup by Spring Boot and family.

    Indexed Settings

    CAS settings able to accept multiple values are typically documented with an index, such as cas.some.setting[0]=value. The index [0] is meant to be incremented by the adopter to allow for distinct multiple configuration blocks.

    Basic Authentication

    The following settings and properties are available from the CAS configuration catalog:

    The configuration settings listed below are tagged as Required in the CAS configuration metadata. This flag indicates that the presence of the setting may be needed to activate or affect the behavior of the CAS feature and generally should be reviewed, possibly owned and adjusted. If the setting is assigned a default value, you do not need to strictly put the setting in your copy of the configuration, but should review it nonetheless to make sure it matches your deployment expectations.

  • cas.server.tomcat.basic-authn.enabled=false
  • Enable Basic authentication for Tomcat.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatBasicAuthenticationProperties.

    The configuration settings listed below are tagged as Optional in the CAS configuration metadata. This flag indicates that the presence of the setting is not immediately necessary in the end-user CAS configuration, because a default value is assigned or the activation of the feature is not conditionally controlled by the setting value.

  • cas.server.tomcat.basic-authn.auth-roles=
  • Add an authorization role, which is a role name that will be permitted access to the resources protected by this security constraint.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatBasicAuthenticationProperties.

  • cas.server.tomcat.basic-authn.patterns=
  • Add a URL pattern to be part of this web resource collection.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatBasicAuthenticationProperties.

  • cas.server.tomcat.basic-authn.security-roles=
  • Security roles for the CAS application.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatBasicAuthenticationProperties.

    Configuration Metadata

    The collection of configuration properties listed in this section are automatically generated from the CAS source and components that contain the actual field definitions, types, descriptions, modules, etc. This metadata may not always be 100% accurate, or could be lacking details and sufficient explanations.

    Be Selective

    This section is meant as a guide only. Do NOT copy/paste the entire collection of settings into your CAS configuration; rather pick only the properties that you need. Do NOT enable settings unless you are certain of their purpose and do NOT copy settings into your configuration only to keep them as reference. All these ideas lead to upgrade headaches, maintenance nightmares and premature aging.

    YAGNI

    Note that for nearly ALL use cases, declaring and configuring properties listed here is sufficient. You should NOT have to explicitly massage a CAS XML/Java/etc configuration file to design an authentication handler, create attribute release policies, etc. CAS at runtime will auto-configure all required changes for you. If you are unsure about the meaning of a given CAS setting, do NOT turn it on without hesitation. Review the codebase or better yet, ask questions to clarify the intended behavior.

    Naming Convention

    Property names can be specified in very relaxed terms. For instance cas.someProperty, cas.some-property, cas.some_property are all valid names. While all forms are accepted by CAS, there are certain components (in CAS and other frameworks used) whose activation at runtime is conditional on a property value, where this property is required to have been specified in CAS configuration using kebab case. This is both true for properties that are owned by CAS as well as those that might be presented to the system via an external library or framework such as Spring Boot, etc. When possible, properties should be stored in lower-case kebab format, such as cas.property-name=value.S ettings and properties that are controlled by the CAS platform directly always begin with the prefix cas. All other settings are controlled and provided to CAS via other underlying frameworks and may have their own schemas and syntax. BE CAREFUL with the distinction. Unrecognized properties are rejected by CAS and/or frameworks upon which CAS depends. This means if you somehow misspell a property definition or fail to adhere to the dot-notation syntax and such, your setting is entirely refused by CAS and likely the feature it controls will never be activated in the way you intend.

    Validation

    Configuration properties are automatically validated on CAS startup to report issues with configuration binding, specially if defined CAS settings cannot be recognized or validated by the configuration schema. The validation process is on by default and can be skipped on startup using a special system property SKIP_CONFIG_VALIDATION that should be set to true. Additional validation processes are also handled via Configuration Metadata and property migrations applied automatically on startup by Spring Boot and family.

    Indexed Settings

    CAS settings able to accept multiple values are typically documented with an index, such as cas.some.setting[0]=value. The index [0] is meant to be incremented by the adopter to allow for distinct multiple configuration blocks.

    Apache Portable Runtime (APR)

    Apache Tomcat can use the Apache Portable Runtime to provide superior scalability, performance, and better integration with native server technologies.

    The following settings and properties are available from the CAS configuration catalog:

    The configuration settings listed below are tagged as Required in the CAS configuration metadata. This flag indicates that the presence of the setting may be needed to activate or affect the behavior of the CAS feature and generally should be reviewed, possibly owned and adjusted. If the setting is assigned a default value, you do not need to strictly put the setting in your copy of the configuration, but should review it nonetheless to make sure it matches your deployment expectations.

  • cas.server.tomcat.apr.enabled=false
  • Enable APR mode.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatApachePortableRuntimeProperties.

  • cas.server.tomcat.apr.ssl-host-config.certificates[0].certificate-chain-file=
  • Name of the file that contains the certificate chain associated with the server certificate used. The format is PEM-encoded. The certificate chain used for Tomcat should not include the server certificate as its first element. Note that when using more than one certificate for different types, they all must use the same certificate chain.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheSslHostConfigCertificateProperties.

  • cas.server.tomcat.apr.ssl-host-config.certificates[0].certificate-file=
  • Name of the file that contains the server certificate. The format is PEM-encoded. In addition to the certificate, the file can also contain as optional elements DH parameters and/or an EC curve name for ephemeral keys, as generated by openssl dhparam and openssl ecparam, respectively. The output of the respective OpenSSL command can be concatenated to the certificate file.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheSslHostConfigCertificateProperties.

  • cas.server.tomcat.apr.ssl-host-config.certificates[0].certificate-key-file=
  • Name of the file that contains the server private key. The format is PEM-encoded. The default value is the value of certificateFile and in this case both certificate and private key have to be in this file (NOT RECOMMENDED).

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheSslHostConfigCertificateProperties.

  • cas.server.tomcat.apr.ssl-host-config.certificates[0].certificate-key-password=
  • The password used to access the private key associated with the server certificate from the specified file.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheSslHostConfigCertificateProperties.

  • cas.server.tomcat.apr.ssl-host-config.enabled=false
  • Enable this host config.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheSslHostConfigProperties.

    The configuration settings listed below are tagged as Optional in the CAS configuration metadata. This flag indicates that the presence of the setting is not immediately necessary in the end-user CAS configuration, because a default value is assigned or the activation of the feature is not conditionally controlled by the setting value.

  • cas.server.tomcat.apr.ssl-ca-certificate-file=
  • SSL CA certificate file.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatApachePortableRuntimeProperties.

  • cas.server.tomcat.apr.ssl-ca-revocation-file=
  • SSL CA revocation file.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatApachePortableRuntimeProperties.

  • cas.server.tomcat.apr.ssl-certificate-chain-file=
  • SSL certificate chain file.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatApachePortableRuntimeProperties.

  • cas.server.tomcat.apr.ssl-certificate-file=
  • SSL certificate file.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatApachePortableRuntimeProperties.

  • cas.server.tomcat.apr.ssl-certificate-key-file=
  • SSL certificate key file.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatApachePortableRuntimeProperties.

  • cas.server.tomcat.apr.ssl-cipher-suite=
  • SSL cipher suite.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatApachePortableRuntimeProperties.

  • cas.server.tomcat.apr.ssl-disable-compression=false
  • Disable SSL compression.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatApachePortableRuntimeProperties.

  • cas.server.tomcat.apr.ssl-honor-cipher-order=false
  • Honor SSL cipher order.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatApachePortableRuntimeProperties.

  • cas.server.tomcat.apr.ssl-host-config.ca-certificate-file=
  • Name of the file that contains the concatenated certificates for the trusted certificate authorities. The format is PEM-encoded.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheSslHostConfigProperties.

  • cas.server.tomcat.apr.ssl-host-config.certificate-verification=require
  • Set to required if you want the SSL stack to require a valid certificate chain from the client before accepting a connection. Set to optional if you want the SSL stack to request a client Certificate, but not fail if one isn't presented. Set to optionalNoCA if you want client certificates to be optional and you don't want Tomcat to check them against the list of trusted CAs. If the TLS provider doesn't support this option (OpenSSL does, JSSE does not) it is treated as if optional was specified. A none value (which is the default) will not require a certificate chain unless the client requests a resource protected by a security constraint that uses CLIENT-CERT authentication.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheSslHostConfigProperties.

  • cas.server.tomcat.apr.ssl-host-config.certificate-verification-depth=10
  • The maximum number of intermediate certificates that will be allowed when validating client certificates. If not specified, the default value of 10 will be used.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheSslHostConfigProperties.

  • cas.server.tomcat.apr.ssl-host-config.certificates=
  • List of certificates managed by the ssl host config.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheSslHostConfigProperties.

  • cas.server.tomcat.apr.ssl-host-config.certificates[0].type=UNDEFINED
  • The type of certificate. This is used to identify the ciphers that are compatible with the certificate. It must be one of UNDEFINED, RSA, DSS or EC. If only one Certificate is nested within a SSLHostConfig then this attribute is not required and will default to UNDEFINED. If multiple Certificates are nested within a SSLHostConfig then this attribute is required and each Certificate must have a unique type.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheSslHostConfigCertificateProperties.

  • cas.server.tomcat.apr.ssl-host-config.host-name=
  • The name of the SSL Host. This should either be the fully qualified domain name (e.g. tomcat.apache.org) or a wild card domain name (e.g. *.apache.org). If not specified, the default value of _default_ will be used.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheSslHostConfigProperties.

  • cas.server.tomcat.apr.ssl-host-config.insecure-renegotiation=false
  • OpenSSL only. Configures if insecure renegotiation is allowed. The default is false. If the OpenSSL version used does not support configuring if insecure renegotiation is allowed then the default for that OpenSSL version will be used.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheSslHostConfigProperties.

  • cas.server.tomcat.apr.ssl-host-config.protocols=all
  • The names of the protocols to support when communicating with clients. This should be a list of any combination of the following:

    • SSLv2Hello
    • SSLv3
    • TLSv1
    • TLSv1.1
    • TLSv1.2
    • TLSv1.3
    • all
    Each token in the list can be prefixed with a plus sign ("+") or a minus sign ("-"). A plus sign adds the protocol, a minus sign removes it form the current list. The list is built starting from an empty list. The token all is an alias for SSLv2Hello,TLSv1,TLSv1.1,TLSv1.2,TLSv1.3. Note that TLSv1.3 is only supported for JSSE when using a JVM that implements TLSv1.3. Note that SSLv2Hello will be ignored for OpenSSL based secure connectors. If more than one protocol is specified for an OpenSSL based secure connector it will always support SSLv2Hello. If a single protocol is specified it will not support SSLv2Hello. Note that SSLv2 and SSLv3 are inherently unsafe. If not specified, the default value of all will be used.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheSslHostConfigProperties.

  • cas.server.tomcat.apr.ssl-host-config.revocation-enabled=false
  • Should the JSSE provider enable certificate revocation checks? This attribute is intended to enable revocation checks that have been configured for the current JSSE provider via other means. If not specified, a default of false is used.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheSslHostConfigProperties.

  • cas.server.tomcat.apr.ssl-host-config.ssl-protocol=TLS
  • The SSL protocol(s) to use (a single value may enable multiple protocols - see the JVM documentation for details). If not specified, the default is TLS. The permitted values may be obtained from the JVM documentation for the allowed values for algorithm when creating an SSLContext instance

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheSslHostConfigProperties.

  • cas.server.tomcat.apr.ssl-password=
  • SSL password (if a cert is encrypted, and no password has been provided, a callback will ask for a password).

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatApachePortableRuntimeProperties.

  • cas.server.tomcat.apr.ssl-protocol=
  • SSL verify client.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatApachePortableRuntimeProperties.

  • cas.server.tomcat.apr.ssl-verify-client=require
  • SSL verify client.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatApachePortableRuntimeProperties.

  • cas.server.tomcat.apr.ssl-verify-depth=10
  • SSL verify depth.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatApachePortableRuntimeProperties.

    Configuration Metadata

    The collection of configuration properties listed in this section are automatically generated from the CAS source and components that contain the actual field definitions, types, descriptions, modules, etc. This metadata may not always be 100% accurate, or could be lacking details and sufficient explanations.

    Be Selective

    This section is meant as a guide only. Do NOT copy/paste the entire collection of settings into your CAS configuration; rather pick only the properties that you need. Do NOT enable settings unless you are certain of their purpose and do NOT copy settings into your configuration only to keep them as reference. All these ideas lead to upgrade headaches, maintenance nightmares and premature aging.

    YAGNI

    Note that for nearly ALL use cases, declaring and configuring properties listed here is sufficient. You should NOT have to explicitly massage a CAS XML/Java/etc configuration file to design an authentication handler, create attribute release policies, etc. CAS at runtime will auto-configure all required changes for you. If you are unsure about the meaning of a given CAS setting, do NOT turn it on without hesitation. Review the codebase or better yet, ask questions to clarify the intended behavior.

    Naming Convention

    Property names can be specified in very relaxed terms. For instance cas.someProperty, cas.some-property, cas.some_property are all valid names. While all forms are accepted by CAS, there are certain components (in CAS and other frameworks used) whose activation at runtime is conditional on a property value, where this property is required to have been specified in CAS configuration using kebab case. This is both true for properties that are owned by CAS as well as those that might be presented to the system via an external library or framework such as Spring Boot, etc. When possible, properties should be stored in lower-case kebab format, such as cas.property-name=value.S ettings and properties that are controlled by the CAS platform directly always begin with the prefix cas. All other settings are controlled and provided to CAS via other underlying frameworks and may have their own schemas and syntax. BE CAREFUL with the distinction. Unrecognized properties are rejected by CAS and/or frameworks upon which CAS depends. This means if you somehow misspell a property definition or fail to adhere to the dot-notation syntax and such, your setting is entirely refused by CAS and likely the feature it controls will never be activated in the way you intend.

    Validation

    Configuration properties are automatically validated on CAS startup to report issues with configuration binding, specially if defined CAS settings cannot be recognized or validated by the configuration schema. The validation process is on by default and can be skipped on startup using a special system property SKIP_CONFIG_VALIDATION that should be set to true. Additional validation processes are also handled via Configuration Metadata and property migrations applied automatically on startup by Spring Boot and family.

    Indexed Settings

    CAS settings able to accept multiple values are typically documented with an index, such as cas.some.setting[0]=value. The index [0] is meant to be incremented by the adopter to allow for distinct multiple configuration blocks.

    Enabling APR requires the following JVM system property that indicates the location of the APR library binaries (i.e. usr/local/opt/tomcat-native/lib):

    1
    
    -Djava.library.path=/path/to/tomcat-native/lib
    

    Connector IO

    The following settings and properties are available from the CAS configuration catalog:

    The configuration settings listed below are tagged as Required in the CAS configuration metadata. This flag indicates that the presence of the setting may be needed to activate or affect the behavior of the CAS feature and generally should be reviewed, possibly owned and adjusted. If the setting is assigned a default value, you do not need to strictly put the setting in your copy of the configuration, but should review it nonetheless to make sure it matches your deployment expectations.

    The configuration settings listed below are tagged as Optional in the CAS configuration metadata. This flag indicates that the presence of the setting is not immediately necessary in the end-user CAS configuration, because a default value is assigned or the activation of the feature is not conditionally controlled by the setting value.

  • cas.server.tomcat.socket.app-read-buf-size=0
  • Each connection that is opened up in Tomcat get associated with a read ByteBuffer. This attribute controls the size of this buffer. By default this read buffer is sized at 8192 bytes. For lower concurrency, you can increase this to buffer more data. For an extreme amount of keep alive connections, decrease this number or increase your heap size.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatSocketProperties.

  • cas.server.tomcat.socket.app-write-buf-size=0
  • Each connection that is opened up in Tomcat get associated with a write ByteBuffer. This attribute controls the size of this buffer. By default this write buffer is sized at 8192 bytes. For low concurrency you can increase this to buffer more response data. For an extreme amount of keep alive connections, decrease this number or increase your heap size. The default value here is pretty low, you should up it if you are not dealing with tens of thousands concurrent connections.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatSocketProperties.

  • cas.server.tomcat.socket.buffer-pool=0
  • The NIO connector uses a class called NioChannel that holds elements linked to a socket. To reduce garbage collection, the NIO connector caches these channel objects. This value specifies the size of this cache. The default value is 500, and represents that the cache will hold 500 NioChannel objects. Other values are -1 for unlimited cache and 0 for no cache.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatSocketProperties.

  • cas.server.tomcat.socket.performance-bandwidth=-1
  • An int expressing the relative importance of high bandwidth. Performance preferences are described by three integers whose values indicate the relative importance of short connection time, low latency, and high bandwidth. The absolute values of the integers are irrelevant; in order to choose a protocol the values are compared, with larger values indicating stronger preferences. Negative values disable the setting. If the application prefers short connection time over both low latency and high bandwidth, for example, then it could invoke this method with the values (1, 0, 0). If the application prefers high bandwidth above low latency, and low latency above short connection time, then it could invoke this method with the values (0, 1, 2).

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatSocketProperties.

  • cas.server.tomcat.socket.performance-connection-time=-1
  • An int expressing the relative importance of a short connection time. Performance preferences are described by three integers whose values indicate the relative importance of short connection time, low latency, and high bandwidth. The absolute values of the integers are irrelevant; in order to choose a protocol the values are compared, with larger values indicating stronger preferences. Negative values disable the setting. If the application prefers short connection time over both low latency and high bandwidth, for example, then it could invoke this method with the values (1, 0, 0). If the application prefers high bandwidth above low latency, and low latency above short connection time, then it could invoke this method with the values (0, 1, 2).

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatSocketProperties.

  • cas.server.tomcat.socket.performance-latency=-1
  • An int expressing the relative importance of low latency. Performance preferences are described by three integers whose values indicate the relative importance of short connection time, low latency, and high bandwidth. The absolute values of the integers are irrelevant; in order to choose a protocol the values are compared, with larger values indicating stronger preferences. Negative values disable the setting. If the application prefers short connection time over both low latency and high bandwidth, for example, then it could invoke this method with the values (1, 0, 0). If the application prefers high bandwidth above low latency, and low latency above short connection time, then it could invoke this method with the values (0, 1, 2).

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatSocketProperties.

    Configuration Metadata

    The collection of configuration properties listed in this section are automatically generated from the CAS source and components that contain the actual field definitions, types, descriptions, modules, etc. This metadata may not always be 100% accurate, or could be lacking details and sufficient explanations.

    Be Selective

    This section is meant as a guide only. Do NOT copy/paste the entire collection of settings into your CAS configuration; rather pick only the properties that you need. Do NOT enable settings unless you are certain of their purpose and do NOT copy settings into your configuration only to keep them as reference. All these ideas lead to upgrade headaches, maintenance nightmares and premature aging.

    YAGNI

    Note that for nearly ALL use cases, declaring and configuring properties listed here is sufficient. You should NOT have to explicitly massage a CAS XML/Java/etc configuration file to design an authentication handler, create attribute release policies, etc. CAS at runtime will auto-configure all required changes for you. If you are unsure about the meaning of a given CAS setting, do NOT turn it on without hesitation. Review the codebase or better yet, ask questions to clarify the intended behavior.

    Naming Convention

    Property names can be specified in very relaxed terms. For instance cas.someProperty, cas.some-property, cas.some_property are all valid names. While all forms are accepted by CAS, there are certain components (in CAS and other frameworks used) whose activation at runtime is conditional on a property value, where this property is required to have been specified in CAS configuration using kebab case. This is both true for properties that are owned by CAS as well as those that might be presented to the system via an external library or framework such as Spring Boot, etc. When possible, properties should be stored in lower-case kebab format, such as cas.property-name=value.S ettings and properties that are controlled by the CAS platform directly always begin with the prefix cas. All other settings are controlled and provided to CAS via other underlying frameworks and may have their own schemas and syntax. BE CAREFUL with the distinction. Unrecognized properties are rejected by CAS and/or frameworks upon which CAS depends. This means if you somehow misspell a property definition or fail to adhere to the dot-notation syntax and such, your setting is entirely refused by CAS and likely the feature it controls will never be activated in the way you intend.

    Validation

    Configuration properties are automatically validated on CAS startup to report issues with configuration binding, specially if defined CAS settings cannot be recognized or validated by the configuration schema. The validation process is on by default and can be skipped on startup using a special system property SKIP_CONFIG_VALIDATION that should be set to true. Additional validation processes are also handled via Configuration Metadata and property migrations applied automatically on startup by Spring Boot and family.

    Indexed Settings

    CAS settings able to accept multiple values are typically documented with an index, such as cas.some.setting[0]=value. The index [0] is meant to be incremented by the adopter to allow for distinct multiple configuration blocks.

    Session Clustering & Replication

    Enable in-memory session replication to replicate web application session deltas.

    Clustering Type Description
    DEFAULT Discovers cluster members via multicast discovery and optionally via staticly defined cluster members using the clusterMembers. SimpleTcpCluster with McastService
    CLOUD For use in Kubernetes where members are discovered via accessing the Kubernetes API or doing a DNS lookup of the members of a Kubernetes service. Documentation is currently light, see code for details.
    Membership Providers Description
    kubernetes Uses Kubernetes API to find other pods in a deployment. API is discovered and accessed via information in environment variables set in the container. The KUBERNETES_NAMESPACE environment variable is used to query the pods in the namespace and it will treat other pods in that namespace as potential cluster members but they can be filtered using the KUBERNETES_LABELS environment variable which are used as a label selector.
    dns Uses DNS lookups to find addresses of the cluster members behind a DNS name specified by DNS_MEMBERSHIP_SERVICE_NAME environment variable. Works in Kubernetes but doesn’t rely on Kubernetes.
    MembershipProvider class Use a membership provider implementation of your choice.

    Most settings apply to the DEFAULT clustering type, which requires members to be defined via clusterMembers if multicast discovery doesn’t work. The cloudMembershipProvider setting applies to the CLOUD type.

    The following settings and properties are available from the CAS configuration catalog:

    The configuration settings listed below are tagged as Required in the CAS configuration metadata. This flag indicates that the presence of the setting may be needed to activate or affect the behavior of the CAS feature and generally should be reviewed, possibly owned and adjusted. If the setting is assigned a default value, you do not need to strictly put the setting in your copy of the configuration, but should review it nonetheless to make sure it matches your deployment expectations.

  • cas.server.tomcat.clustering.enabled=false
  • Enable tomcat session clustering.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatClusteringProperties.

    The configuration settings listed below are tagged as Optional in the CAS configuration metadata. This flag indicates that the presence of the setting is not immediately necessary in the end-user CAS configuration, because a default value is assigned or the activation of the feature is not conditionally controlled by the setting value.

  • cas.server.tomcat.clustering.channel-send-options=8
  • This option is used to set the flag that all messages sent through the SimpleTcpCluster uses. The flag decides how the messages are sent, and is a simple logical OR.

    • 2: SEND_OPTIONS_SYNCHRONIZED_ACK
    • 4: SEND_OPTIONS_USE_ACK
    • 8: SEND_OPTIONS_ASYNCHRONOUS

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatClusteringProperties.

  • cas.server.tomcat.clustering.cloud-membership-provider=dns
  • Cloud membership provider, values are case sensitive and only used with clusteringType CLOUD. The different providers rely on environment variables to discover other members of cluster via DNS lookups of the service name or querying kubernetes API. See code or Tomcat documentation for the environment variables that are used.

    • kubernetes will use org.apache.catalina.tribes.KubernetesMembershipProvider
    • dns will use org.apache.catalina.tribes.DNSMembershipProvider
    • Class implementing org.apache.catalina.tribes.MembershipProvider

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatClusteringProperties.

  • cas.server.tomcat.clustering.cluster-members=
  • Statically register members in the cluster. The syntax is: address:port:index

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatClusteringProperties.

  • cas.server.tomcat.clustering.clustering-type=DEFAULT
  • Accepted values are: DEFAULT, CLOUD. Type of clustering to use, set to CLOUD if using CloudMembershipService.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatClusteringProperties.

  • cas.server.tomcat.clustering.expire-sessions-on-shutdown=false
  • When a web application is being shutdown, Tomcat issues an expire call to each session to notify all the listeners. If you wish for all sessions to expire on all nodes when a shutdown occurs on one node, set this value to true. Default value is false.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatClusteringProperties.

  • cas.server.tomcat.clustering.manager-type=DELTA
  • Accepted values are: DELTA, BACKUP. Enable all-to-all session replication using the DeltaManager to replicate session deltas. By all-to-all we mean that the session gets replicated to all the other nodes in the cluster. This works great for smaller cluster but we don't recommend it for larger clusters(a lot of Tomcat nodes). Also when using the delta manager it will replicate to all nodes, even nodes that don't have the application deployed. To get around this problem, you'll want to use the BackupManager. This manager only replicates the session data to one backup node, and only to nodes that have the application deployed. Downside of the BackupManager: not quite as battle tested as the delta manager.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatClusteringProperties.

  • cas.server.tomcat.clustering.membership-address=228.0.0.4
  • Multicast address for membership. The multicast address that the membership will broadcast its presence and listen for other heartbeats on. The default value is 228.0.0.4 Make sure your network is enabled for multicast traffic. The multicast address, in conjunction with the port is what creates a cluster group. To divide up your farm into several different group, or to split up QA from production, change the port or the address

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatClusteringProperties.

  • cas.server.tomcat.clustering.membership-drop-time=3000
  • The membership component will time out members and notify the Channel if a member fails to send a heartbeat within a give time. The default value is 3000 ms. This means, that if a heartbeat is not received from a member in that timeframe, the membership component will notify the cluster of this. On a high latency network you may wish to increase this value, to protect against false positives. Apache Tribes also provides a TcpFailureDetector that will verify a timeout using a TCP connection when a heartbeat timeout has occurred. This protects against false positives.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatClusteringProperties.

  • cas.server.tomcat.clustering.membership-frequency=500
  • The frequency in milliseconds in which heartbeats are sent out. The default value is 500 ms. In most cases the default value is sufficient. Changing this value, changes the interval in between heartbeats.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatClusteringProperties.

  • cas.server.tomcat.clustering.membership-local-loopback-disabled=false
  • Membership uses multicast, it will call java.net.MulticastSocket.setLoopbackMode(localLoopbackDisabled). When localLoopbackDisabled==true multicast messages will not reach other nodes on the same local machine. The default is false.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatClusteringProperties.

  • cas.server.tomcat.clustering.membership-port=45564
  • Multicast port (the port and the address together determine cluster membership. The multicast port, the default value is 45564 The multicast port, in conjunction with the address is what creates a cluster group. To divide up your farm into several different group, or to split up QA from production, change the port or the address

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatClusteringProperties.

  • cas.server.tomcat.clustering.membership-recovery-counter=10
  • Membership uses multicast, it will call java.net.MulticastSocket.setLoopbackMode(localLoopbackDisabled). When localLoopbackDisabled==true multicast messages will not reach other nodes on the same local machine. The default is false.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatClusteringProperties.

  • cas.server.tomcat.clustering.membership-recovery-enabled=true
  • In case of a network failure, Java multicast socket don't transparently fail over, instead the socket will continuously throw IOException upon each receive request. When recovery-enabled is set to true, this will close the multicast socket and open a new socket with the same properties as defined above. The default is true.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatClusteringProperties.

  • cas.server.tomcat.clustering.receiver-address=auto
  • The address (network interface) to listen for incoming traffic.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatClusteringProperties.

  • cas.server.tomcat.clustering.receiver-auto-bind=100
  • Default value is 100. Use this value if you wish to automatically avoid port conflicts the cluster receiver will try to open a server socket on the port attribute port, and then work up autoBind number of times.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatClusteringProperties.

  • cas.server.tomcat.clustering.receiver-max-threads=6
  • Maximum threads configured for the listener. The maximum number of threads in the receiver thread pool. The default value is 6 Adjust this value relative to the number of nodes in the cluster, the number of messages being exchanged and the hardware you are running on. A higher value doesn't mean more efficiency, tune this value according to your own test results.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatClusteringProperties.

  • cas.server.tomcat.clustering.receiver-port=4000
  • The listen port for incoming data. The default value is 4000. To avoid port conflicts the receiver will automatically bind to a free port. So for example, if port is 4000, and autoBind is set to 10, then the receiver will open up a server socket on the first available port in the range 4000-4009.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatClusteringProperties.

  • cas.server.tomcat.clustering.receiver-timeout=5000
  • Listener timeout. The value in milliseconds for the polling timeout in the NioReceiver. On older versions of the JDK there have been bugs, that should all now be cleared out where the selector never woke up. The default value is a very high 5000 milliseconds.

    org.apereo.cas.configuration.model.core.web.tomcat.CasEmbeddedApacheTomcatClusteringProperties.

    Configuration Metadata

    The collection of configuration properties listed in this section are automatically generated from the CAS source and components that contain the actual field definitions, types, descriptions, modules, etc. This metadata may not always be 100% accurate, or could be lacking details and sufficient explanations.

    Be Selective

    This section is meant as a guide only. Do NOT copy/paste the entire collection of settings into your CAS configuration; rather pick only the properties that you need. Do NOT enable settings unless you are certain of their purpose and do NOT copy settings into your configuration only to keep them as reference. All these ideas lead to upgrade headaches, maintenance nightmares and premature aging.

    YAGNI

    Note that for nearly ALL use cases, declaring and configuring properties listed here is sufficient. You should NOT have to explicitly massage a CAS XML/Java/etc configuration file to design an authentication handler, create attribute release policies, etc. CAS at runtime will auto-configure all required changes for you. If you are unsure about the meaning of a given CAS setting, do NOT turn it on without hesitation. Review the codebase or better yet, ask questions to clarify the intended behavior.

    Naming Convention

    Property names can be specified in very relaxed terms. For instance cas.someProperty, cas.some-property, cas.some_property are all valid names. While all forms are accepted by CAS, there are certain components (in CAS and other frameworks used) whose activation at runtime is conditional on a property value, where this property is required to have been specified in CAS configuration using kebab case. This is both true for properties that are owned by CAS as well as those that might be presented to the system via an external library or framework such as Spring Boot, etc. When possible, properties should be stored in lower-case kebab format, such as cas.property-name=value.S ettings and properties that are controlled by the CAS platform directly always begin with the prefix cas. All other settings are controlled and provided to CAS via other underlying frameworks and may have their own schemas and syntax. BE CAREFUL with the distinction. Unrecognized properties are rejected by CAS and/or frameworks upon which CAS depends. This means if you somehow misspell a property definition or fail to adhere to the dot-notation syntax and such, your setting is entirely refused by CAS and likely the feature it controls will never be activated in the way you intend.

    Validation

    Configuration properties are automatically validated on CAS startup to report issues with configuration binding, specially if defined CAS settings cannot be recognized or validated by the configuration schema. The validation process is on by default and can be skipped on startup using a special system property SKIP_CONFIG_VALIDATION that should be set to true. Additional validation processes are also handled via Configuration Metadata and property migrations applied automatically on startup by Spring Boot and family.

    Indexed Settings

    CAS settings able to accept multiple values are typically documented with an index, such as cas.some.setting[0]=value. The index [0] is meant to be incremented by the adopter to allow for distinct multiple configuration blocks.